.. _Install:

Install and setup
=================

Spinal is a Scala library so it requires setting up a Scala environment; there
are many ways to do so. Also, it generates VHDL, Verilog or SystemVerilog, which
can be used by many different tools. This section describes the supported way to
install a *SpinalHDL description to Simulation* flow, but there can be many
variations.


Mandatory requirements
----------------------

Before you download the SpinalHDL tools, you need to install a Scala environment:

* `Java JDK <https://www.oracle.com/java/technologies/downloads/>`_, a Java
  environment
* `SBT <https://www.scala-sbt.org/download.html>`_, a Scala build tool

For instance, to install them on the Debian distribution:

.. code-block:: sh

   sudo apt-get install openjdk-8-jdk
   sudo apt-get install scala
   echo "deb https://repo.scala-sbt.org/scalasbt/debian all main" | sudo tee /etc/apt/sources.list.d/sbt.list
   echo "deb https://repo.scala-sbt.org/scalasbt/debian /" | sudo tee /etc/apt/sources.list.d/sbt_old.list
   curl -sL "https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x2EE0EA64E40A89B84B2DF73499E82A75642AC823" | sudo apt-key add
   sudo apt-get update
   sudo apt-get install sbt

These tools enable to use Spinal; but without any other tools, it is limited to
code generation.


Installing SBT in an internet-free environment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. note::
   If you do not need this, you can skip to the next section:
   :ref:`recommended`.

Normally, SBT uses online repositories to download and cache your projects
dependencies. This cache is located in several folders:

* ``~/.sbt``
* ``~/.cache/JNA``
* ``~/.cache/coursier``

To set up an internet-free environment, you can:

#. Set up an environment with internet
#. Launch a Spinal command (see :ref:`Using SBT`) to fetch dependencies (for
   instance using the `getting started
   <https://github.com/SpinalHDL/SpinalTemplateSbt>`_ repository)
#. Copy the caches to the internet-free environment.

.. note::
   You can get a portable SBT setup here: https://www.scala-sbt.org/download.html

.. note::
   You might be interested in `SpinalNomad <https://github.com/SpinalHDL/SpinalNomad/tree/main/sbt>`_.


.. _recommended:

Recommended requirements
------------------------

To enable more features:

* An IDE (for instance `IntelliJ <https://www.jetbrains.com/idea/>`_ with its
  Scala plugin or `VSCodium <https://vscodium.com/>`_ with Metals extension) to
  get features such as:

    * Code suggestions / completion
    * Automatic build with syntax errors right in the code
    * Generate code with a single click
    * Run simulation / tests with a single click (if a supported simulator is
      set up)

* A supported simulator like `Verilator <https://www.veripool.org/verilator/>`_
  to test the design right from SpinalHDL.
* `Gtkwave <https://gtkwave.sourceforge.net/>`_ to view the waves generated by
  Verilator during simulation.
* `Git <https://git-scm.com/>`_ for version control system


.. _template:

Create a SpinalHDL project
--------------------------

We have prepared a ready-to-go project for you the: `getting started <https://github.com/SpinalHDL/SpinalTemplateSbt>`_ repository.

You can `download <https://codeload.github.com/SpinalHDL/SpinalTemplateSbt/zip/master>`_ it, or clone it.

The following commands clone the project into a new directory named
``MySpinalProject`` and initialize a fresh ``git`` history:

.. code-block:: sh

   git clone --depth 1 https://github.com/SpinalHDL/SpinalTemplateSbt.git MySpinalProject
   cd MySpinalProject
   rm -rf .git
   git init
   git add .
   git commit -m "Initial commit from template"


The directory structure of a project
------------------------------------

.. note::

   The structure described here is the default structure, but it can be easily
   modified.

In the root of the project are the following files:

================== ===========================================================
File               Description
================== ===========================================================
``build.sbt``      Scala configuration for ``sbt``
``build.sc``       Scala configuration for ``mill``, an alternative to ``sbt``
``hw/``            The folder containing hardware descriptions
``project/``       More Scala configuration
``README.md``      A ``text/markdown`` file describing your project
``.gitignore``     List of files to ignore in versioning
``.mill-version``  More configuration for ``mill``
``.scalafmt.conf`` Configuration of rules to auto-format the code
================== ===========================================================

As you probably guessed it, the interesting thing here is ``hw/``. It contains
four folders: ``spinal/``, ``verilog/`` and ``vhdl/`` for your IPs and ``gen/``
for IPs generated with Spinal.

``hw/spinal/`` contains a folder named after your project name. This name must
be set in ``build.sbt`` (along with the company name) and in ``build.sc``; and
it must be the one in ``package yourprojectname`` at the beginning of ``.scala``
files.

In ``hw/spinal/yourprojectname/``, are the descriptions of your IPs, simulation
tests, formal tests; and there is ``Config.scala``, which contains the
configuration of ``Spinal``.

.. note::

   ``sbt`` must be used **only** at the root of the project, in the folder
   containing ``build.sbt``.


Using Spinal on SpinalHDL code
------------------------------

Now the tutorial shows how to use Spinal on SpinalHDL code depending on your
development environment:

* :ref:`Using SBT`
* :ref:`Using VSCodium`
* :ref:`Using IntelliJ`